# ROS 2 Humble安装指南

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

本文档说明在 Quectel Pi M1 开发板（Debian 13 trixie / ARM64）上从源码构建 ROS 2 Humble 的方法。ROS 2 Humble 官方发行版面向 Ubuntu 22.04，Debian 13 下无现成 apt 包，需在板端从源码构建。本文档所有步骤均在 M1（内核 5.15.180-gki-consolidate，Python 3.13.5）上实测通过。

## 简介

ROS 2（Robot Operating System 2）是面向机器人开发的分布式通信框架，Humble 为其长期支持（LTS）版本。在 M1 开发板上从源码构建 ROS 2 Humble 的特点：

- 可裁剪：只构建需要的功能包，可跳过 Fast DDS、Connext 等商业中间件（本文档使用 Cyclone DDS）；

- 板端验证：直接基于 M1 的 Debian 13 系统构建，产物与硬件环境匹配；

- 可复现：工作空间结构与构建参数可模板化，便于 CI 与多设备同步。

**磁盘空间提示：** M1 根分区（/）仅 7.8 GB，完整编译需 10 GB 以上空间。本文档将工作空间部署在 `/data` 分区（约 40 GB，SD 卡 mmcblk0p82），编译全程实测无空间压力。

## 准备工作

### 系统要求

| **项目** | **要求** |
| --- | --- |
| 操作系统 | Debian GNU/Linux 13 (trixie) |
| 架构 | ARM64（aarch64） |
| 磁盘 | 建议部署在 /data 分区（根分区空间不足）；源码约 1 GB，编译产物约 3 GB |
| 内存 | ≥ 3 GB（M1 为 3.5 GB，编译较慢但可用） |
| 网络 | 可访问 GitHub（克隆源码）与 Debian 软件源（安装依赖） |
| 编译时间 | 约 3–5 小时（M1 实测，含排障） |

### 网络环境（内网/无外网场景）

若板子无法直连外网，可通过 **宿主机代理 + adb reverse** 提供网络：

```bash
# 宿主机：启动 HTTP 代理（如 python 简易代理，监听 3128）
# 板子：通过 adb reverse 将板内 3128 端口转发到宿主机
adb reverse tcp:3128 tcp:3128

# 板子上设置代理环境变量
export http_proxy=http://127.0.0.1:3128 https_proxy=http://127.0.0.1:3128
export HTTP_PROXY=http://127.0.0.1:3128 HTTPS_PROXY=http://127.0.0.1:3128

# 配置 apt 使用代理
echo 'Acquire::http::Proxy "http://127.0.0.1:3128";' > /etc/apt/apt.conf.d/01proxy
echo 'Acquire::https::Proxy "http://127.0.0.1:3128";' >> /etc/apt/apt.conf.d/01proxy

```

**注意：** 板子默认时间可能错误（1970 年），会导致 HTTPS 证书校验失败，需先同步时间：`date -s "$(date '+%Y-%m-%d %H:%M:%S')"`（或配置 NTP）。

## 安装步骤

### 安装基础依赖包

```bash
sudo apt-get update
sudo apt-get install -y \
    python3-flake8-blind-except python3-flake8-class-newline python3-flake8-deprecated \
    python3-mypy python3-pip python3-pytest python3-pytest-cov python3-pytest-mock \
    python3-pytest-repeat python3-pytest-rerunfailures python3-pytest-runner \
    python3-pytest-timeout python3-rosdep2 python3-colcon-core \
    vcstool build-essential git \
    python3-numpy python3-numpy-dev \
    libacl1-dev uncrustify

```

### 创建工作空间（部署到 /data）

```bash
# 根分区空间不足时，使用 /data 分区并建软链
sudo mkdir -p /data/ros2_humble/src
sudo ln -s /data/ros2_humble /root/ros2_humble
cd /data/ros2_humble

```

### 获取 ROS 2 Humble 源代码

```bash
cd /data/ros2_humble
mkdir -p src
wget https://raw.githubusercontent.com/ros2/ros2/humble/ros2.repos
vcs import src < ros2.repos

```

ros2.repos 包含约 100 个仓库（实测 105 个），源码约 600 MB。若 vcs 卡在某仓库（如 Fast-DDS 大仓库），可改用浅克隆脚本逐个拉取。

### 安装系统依赖项

```bash
sudo rosdep init
rosdep update
cd /data/ros2_humble
rosdep install --from-paths src --ignore-src --rosdistro humble -y -r \
  --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-vcstool \
              ignition-math6 ignition-cmake2 ignition-common3 ignition-transport8"

```

**跳过的包说明：** fastcdr、rti-connext-dds（商业/可选）；urdfdom_headers、python3-vcstool（已装）；ignition-*（Debian 13 不可用，Gazebo 相关）。

**常见错误（可忽略）：** python3-sip-dev 失败（GUI 工具 rqt 依赖）、python3-nose 失败（Python 3.12+ 废弃），均不影响核心功能。

### 编译源码

**编译策略：** 使用 Cyclone DDS（跳过 Fast DDS/Connext 编译，显著减少耗时与空间），只构建到 demo_nodes 的最小依赖链：

```bash
cd /data/ros2_humble
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

colcon build --symlink-install \
  --packages-up-to demo_nodes_cpp demo_nodes_py \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF \
  --packages-skip \
  rmw_connextdds rmw_connextdds_common rmw_connextddsmicro rti_connext_dds_cmake_module \
  rviz_assimp_vendor tinyxml_vendor libcurl_vendor zstd_vendor sqlite3_vendor \
  yaml_cpp_vendor shared_queues_vendor

```

实测编译约 130 个包、耗时 40+ 分钟（含大包 fastrtps 26 分钟、iceoryx_posh 等）。编译完成后可追加构建 `ros2cli` 命令行工具：

```bash
source /data/ros2_humble/install/setup.bash
colcon build --packages-select ros2cli ros2node ros2topic ros2msg ros2service ros2action ros2param \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

```

### 编译问题与解决方法（M1 实测）

**问题 1：rmw 编译报 unknown type name 'bool'**

新版 GCC 更严格，`rmw/time.h` 缺 `#include <stdbool.h>`。修复：

```bash
sed -i 's|#include <stdint.h>|#include <stdbool.h>\n#include <stdint.h>|' \
  /data/ros2_humble/src/ros2/rmw/rmw/include/rmw/time.h

```

**问题 2：vendor 包（zstd/sqlite3/yaml_cpp 等）下载超时被 abort**

这些包编译时从外网下载第三方源码，代理不稳会失败。解决：预先用代理下载归档到 CMake 缓存路径（`build/`<pkg>`/*-prefix/src/`），文件存在且 MD5 匹配时 CMake 会跳过下载；超大文件（如 assimp 45 MB）可在宿主机下载后 adb push 到板子。

**问题 3：rmw_implementation 报 Failed to find .../package.sh**

构建系统查找被跳过包的 package.sh 环境钩子。用占位脚本绕过：

```bash
for p in rti_connext_dds_cmake_module rmw_connextdds_common rmw_connextdds rmw_connextddsmicro; do
  mkdir -p /data/ros2_humble/install/$p/share/$p
  printf '#!/bin/sh\n# placeholder for %s\n' "$p" > /data/ros2_humble/install/$p/share/$p/package.sh
  chmod +x /data/ros2_humble/install/$p/share/$p/package.sh
done

```

**问题 4：rclpy 编译报 Imported target "pybind11::headers" includes non-existent path "/include"**

Debian 打包 pybind11 的 CMake 前缀路径 bug。修复 pybind11Targets.cmake 硬编码 include 路径：

```bash
sed -i 's|INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include"|INTERFACE_INCLUDE_DIRECTORIES "/usr/include"|' \
  /usr/lib/cmake/pybind11/pybind11Targets.cmake

```

**问题 5：消息包编译报 ModuleNotFoundError**

缺 lark（rosidl_parser 依赖）与 numpy C 头文件：

```bash
pip3 install lark netifaces
apt-get install -y python3-numpy-dev   # 提供 numpy/ndarrayobject.h

```

**问题 6：rosidl_cli 反复报 File exists (package.dsv)**

symlink-install 模式对 Python 包资源文件的已知冲突。先单独用 copy 模式构建：

```bash
rm -rf build/rosidl_cli install/rosidl_cli
colcon build --packages-select rosidl_cli \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

```

**问题 7：iceoryx_posh 编译超时被 abort**

该包编译需 5–10 分钟，并行构建时会被 colcon 判定超时。先单独构建：

```bash
colcon build --packages-select iceoryx_posh \
  --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

```

**问题 8：rosidl_default_generators 依赖 rosidl_generator_rs（Rust）**

demo_nodes 不需要 Rust 生成器。从 package.xml 移除该依赖行：

```bash
sed -i '/rosidl_generator_rs/d' \
  /data/ros2_humble/src/ros2/rosidl_defaults/rosidl_default_generators/package.xml

```

## 环境变量设置

编译完成后，将 ROS 2 环境写入 `~/.bashrc` 实现自动加载：

```bash
echo 'source /data/ros2_humble/install/setup.bash' >> ~/.bashrc
echo 'export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp' >> ~/.bashrc
source ~/.bashrc

```

## 使用测试

打开一个终端，运行 C++ talker：

```bash
ros2 run demo_nodes_cpp talker

```

打开另一个终端，运行 Python listener：

```bash
ros2 run demo_nodes_py listener

```

### 验证

M1 实测输出：

```
[INFO] [talker]: Publishing: 'Hello World: 3'
[INFO] [listener]: I heard: [Hello World: 13]

```

也可用 ros2 命令行验证话题：

```bash
ros2 topic list          # 应显示 /chatter /parameter_events /rosout
ros2 topic info /chatter # Type: std_msgs/msg/String, Publisher count: 1

```

C++ 与 Python API 互通正常，ROS 2 Humble 环境可用于后续应用开发。

## 常见问题

### ros2 命令只显示 daemon/extension_points

说明 ros2cli 扩展命令（node/topic 等）未安装。按 3.5 节补充构建 ros2cli 系列包。

### ros2 topic 报 No module named 'netifaces'

```bash
pip3 install netifaces

```

### talker 启动报缺 liblibstatistics_collector.so

未 source 环境导致 LD_LIBRARY_PATH 缺失。先 `source /data/ros2_humble/install/setup.bash` 再运行。

### 编译时内存不足（OOM）

M1 内存 3.5 GB，并行编译可能 OOM。可减少并行度：`colcon build --parallel-workers 2 ...`，或按 3.5 节先单独构建大包。

### 板子时间错误导致 HTTPS 失败

```bash
sudo date -s "$(date '+%Y-%m-%d %H:%M:%S')"

```

### 完整 ros2 功能包（rviz2 等）

本文档为最小化安装（demo_nodes 依赖链）。如需 GUI/仿真功能，可继续用 `colcon build --packages-up-to rviz2 ...` 增量构建（注意磁盘空间）。